JavaScript

{grid.object}gridFilterSet Method

Syntax

{grid.object}.gridFilterSet(filterExpression, [ orderExpression [, filterParameters]]);

Arguments

filterExpressionstring

An expression used to filter records in the Grid component. If the Grid is based on DBF files, use Xbasic syntax for the expression. If the Grid is based on a SQL data source, use SQL syntax for the expression.

orderExpressionstring

Default = "". An expression describing how to order the records in the match the filterExpression. If the Grid is based on DBF files, use Xbasic syntax for the expression. If the Grid is based on a SQL data source, use SQL syntax for the expression.

filterParametersstring

Default = "". A list of one or more newline ('\n') separated filter parameters defined using the following syntax: value|||type|parameterName. The type can be one of the following Xbasic types:

Type: Description
B: Blob
C: Character
D: Date
K: GUID
L: Logical
N: Number
T: Time
Y: Short time

Description

Set an explicit filter and/or order for the Grid Component.

Discussion

The {grid.object}.gridFilterSet() method sets and explicit filter and/or order expression for the Grid component. The expression syntax used for the filter and order expressions is determined by the Grid component's data source. If the Grid is based on DBF tables, Xbasic syntax should be used. Otherwise, expressions should use SQL syntax.

//Filter the Grid to show orders above $1,000, ordered by orderTotal.
{grid.object}.gridFilterSet('ordertotal > 1000');

//Sort the Grid by Lastname and within Lastname, by Firstname. (SQL Table)
{grid.object}.gridFilterSet('','Lastname, Firstname');

//Sort the Grid by Lastname and within Lastname, by Firstname. (DBF Table)
{grid.object}.gridFilterSet('','Lastname+Firstname');

The filter and order expression must be enclosed in single quotes. Therefore if your filter uses single quotes you must escape the single quote. e.g. 'customername = \'smith\''.

Alternatively, you can use double quotes to enclose the JavaScript string. e.g. "customername = 'smith'".

You cannot use double quotes in the filter as it will cause a Javascript error. To prevent unintentional errors created from using double quotes in filter or order expressions, use arguments in the filter or order expressions. The argument values can be supplied using the filterParameters parameter.

If you use arguments in the filter (e.g. orderdate = :whatOrderdate), then you can specify parameter values with the filterParameters argument. The syntax for parameters is a '\n' (Javascript CRLF character) delimited string with value|||type|parameterName. For example:

//Search for records where City is 'London'. Order result by 'Contactname' 
var filter = 'city = :whatCity';
var order = 'Contactname';
var filterParameters = 'london|||c|whatCity';

{grid.object}.gridFilterSet(filter, order, filterParameters);

In the example below, the filter uses 2 arguments (:whatCity and :whatCountry). Therefore the third parameter passed into the method defines these two arguments. Each argument is delimited with '\n' - the Javascript encoding of a CRLF character.

//Search for records where City is 'London' and Country is 'UK'
var filter = 'city = :whatCity and country = :whatCountry';
var order = '';
var filterParameters = ['london|||c|whatCity','uk|||c|whatcountry'];

// join filterParameters array into a '\n' delimited list:
filterParameters = filterParameters.join('\n');

{grid.object}.gridFilterSet(filter, order, filterParameters);